<html>

<head>
 <link rel="stylesheet" type="text/css" href="doc-styles.css"></link>
 <title>glScript API Reference</title> 
</head>
 
<body>
<h3>glScript API Reference</h3>

<a href="index.html">Index</a>

<h4>Contents:</h4>
<ul>
 <li><a href="#glscript_preprocessing">Script Preprocessing</a></li>
 <li>
	<a href="#glscript_inbuilt_objects">Inbuilt Objects</a>
	<ul>
		<li><a href="#glscript_gls_object">gls</a></li>
		<li><a href="#glscript_gl_object">gl</a></li>
		<li><a href="#glscript_console_object">console</a></li>
	</ul>
 </li>
 <li>
	<a href="#glscript_inbuilt_interfaces">Inbuilt Interfaces</a>
	<ul>
		<li><a href="#glscript__GLScript_Array_interface">_GLScript_Array</a></li>
	</ul> 
 </li>
 <li>
	<a href="#glscript_events">glScript Events</a>
	<ul>
		<li><a href="#glscript_basic_events">Basic Events</a></li>
		<li><a href="#glscript_ui_events">UI Events</a></li>
	</ul> 
 </li>
</ul>

<a name="glscript_preprocessing"><h4>Script Preprocessing</h4></a>
<p>
glScript, like many languages, supports preprocessing of scripts. You can perform tasks like
including other scripts, setting preferred script language, etc. during the preprocessing.
This feature makes glScript a powerful tool. Script preprocessing happens before the script source
is handed over to the real script engine that understands the code. glScript engine runs through 
the entire script and finds preprocessor blocks, which contains commands known as preprocessor
directives or simply directives. glScript then processes each block and executes the commands.
Of course, these commands are not specific to any scripting language. glScript also expands the
block if it contains commands to include other scripts. When the preprocessing completes, the 
script is transformed into a single script without any preprocessor block i.e. the script is
expanded or flattened and ready for execution by the scripting engine.
</p>
<p>
A valid preprocessor block is defined by <code>&lt;# #&gt;</code> i.e. it starts from <code>&lt;#</code> pair of symbols 
and ends at <code>#&gt;</code>. There cannot by any space between the pair of symbols i.e. <code>&lt; #</code> is invalid.
The <code>&lt;#</code> and <code>#&gt;</code> pairs may be placed at different lines in the script.
All directives must be enclosed within the body of these tags. A script may have multiple preprocessor blocks,
without any nesting.
</p>

<a name="glscript_directives"><h5>glScript directives</h5></a>
<p>
glScript directives are commands processed by the glScript engine rather than the scripting engine.
glScript directive, for e.g. can tell the glScript engine to include other script files in a program.
These directives are processed during preprocessing of scripts and must be placed within a preprocessor
block <code>&lt;#</code> and <code>#&gt;</code>. Example:
<pre><code><#
language "vbs"
include "splash-screen.gls"
include "info-screen.gls"
#>
</code></pre>
</p>

<a name="glscript_language_directives"><h5>language Directive</h5></a>
<p>
Syntax: <code>language "language-name"</code>
</p>
<p>
<code>language</code> directive sets the language for the current script code. It is usually set, but not necessarily,
in the beginning of the script. You can either set the full language name like 'JavaScript', 'JScript', 'VBScript' etc.
or associated file extension name like 'js', 'vbs' etc. The <code>language</code> directive is optional and if not used, the
language is determined from the script's extension file name. The <code>language</code> directive must be used only once 
throughout the whole preprocessing phase, otherwise.
<p>
<p>
Examples:<pre><code><# language "js" #>
<# language "JScript" #>
<# language "VBScript" #>
</code></pre>
</p>

<h5>include Directive</h5>
<p>
Syntax: <code>include "path"</code>
</p>
<p>
<code>include</code> directive includes other script files into your program. The <code>include</code> directive can be used
anywhere in the program where the desired script is to be included. E.g.
<pre><code><# include "my_lib.js" #>
</code></pre>
</p>

<a name="glscript_inbuilt_objects"><h4>Inbuilt Objects</h4></a>
<p>
glScript provides following inbuilt objects that are always available in your script.
</p>

<ul>
 <li>gls</li>
 <li>gl (auto accessible)</li>
 <li>console</li>
</ul>

<a name="glscript_gls_object"><h4>gls Object</h4></a>
<p>
<code>gls</code> object provides access to glScript internal engine and is used to initialize environment 
settings and perform basic tasks.
</p>

   <a name="glscript_gls_object_properties"><h5>gls Object Properties</h5></a>
   
   <div class="properties">
   <div class="property">
	<div class="syntax">gls.native = flag</div>
    <div class="doc">Enables the native rendering mode (Default = false)</div>
   </div>
   
   <div class="property">
   <div class="syntax">gls.windowTitle = value</div>
   <div class="doc">Sets the title of display window (Default = 'script file name'). 
	Maximum length allowed is 255 characters.</div>
   </div>
   
   <div class="property">
   <div class="syntax">gls.windowWidth = value</div>
   <div class="doc">Sets the width of display window (Default = 480)</div>
   </div>

   <div class="property">
   <div class="syntax">gls.windowHeight = value</div>
   <div class="doc">Sets the height of display window (Default = 320)</div>
   </div>

   <div class="property">
    <div class="syntax">gls.viewportLeft = value</div>
	<div class="doc">Sets the viewport left (Default = 0)</div>
   </div>

   <div class="property">
    <div class="syntax">gls.viewportTop = value</div>
	<div class="doc">Sets the viewport top (Default = 0)</div>
   </div>

   <div class="property">
    <div class="syntax">gls.viewportWidth = value</div>
	<div class="doc">Sets the viewport width (Default = 480)</div>
   </div>

   <div class="property">
   <div class="syntax">gls.viewportHeight = value</div>
   <div class="doc">Sets the viewport height (Default = 320)</div>
   </div>
	
   <div class="property">
	<div class="syntax">gls.ortho = flag</div>
    <div class="doc">Enables or disables orthographic view. (Default = false)</div>
   </div>

   <div class="property">
    <div class="syntax">gls.animation = flag</div>
	<div class="doc">Enables or disables animation. (Default = false)</div>
   </div>

   <div class="property">
   <div class="syntax">gls.frameRate = rate</div>
   <div class="doc">Sets desired frame rate in fps for animation. (Default = 12)</div>
   </div>

   <div class="property">
   <div class="syntax">gls.gles</div>
   <div class="doc"><b>This property is reserved for future use.</b></div>
   </div>

   <div class="property">
    <div class="syntax">gls.glver</div>
	<div class="doc"><b>This property is reserved for future use.</b></div>
   </div>

   <div class="property">
    <div class="syntax">gls.fps (Readonly)</div>
	<div class="doc">Returns the current frame rate in frames per second.</div>
   </div>   
  </div>
  <!-- end gls properties -->
 
<a name="glscript_gls_object_methods"><h5>gls Object Methods</h5></a>
<div class="methods">
   <div class="method">
	<div class="syntax">gls.require (name, [options])</div>
	<div class="doc">
		<p>Loads a dynamic glScript extension.</p>
		<p>Extension loading options can be specified as a string of options delimeted by comma as shown below:
		</p>
		<p>
		<code>"renderer,library"</code>
		</p>
		<p>
		<code>library</code> is the default option if the <code>options</code> parameter is not used. It loads the 
		extension and returns its lib interface.
		</p>
		<p>
		<code>renderer</code> option tells the glScript engine to load the extension and hook its 
		render procedure for performing native drawing of scenes. Note that using the <code>renderer</code> option only,
		will not return any lib interface. Examples:
		</p>
		<p>
		<code>
		var glu = gls.require ("glu"); // load as library by default <br />
		var obj = gls.require ("obj", "library"); <br />
		var animator = gls.require ("animator", "library,renderer");
		</code>
		</p>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax"><a name="glscript_gls_object_method_byteArray">gls.byteArray (elements | size)</a></div>
	<div class="doc">Creates an array of GLbyte.</div>
	<div class="doc">
		<p>You can either use <code>elements</code> or <code>size</code> to create the array.</p>
		
		<p>elements: String containing comma separated elements for the array e.g. "10,20,30". Currently, for integers, 
		each element must be specified in decimal format . Future versions will support other formats like
		hexadecimal and octal.
		
		If you use <code>elements</code> then the array size is automatically determined from the number 
		of values passed in the <code>elements</code> string and the array is filled with the values.
		</p>
		
		<p>size: Size of the array. If you use <code>size</code> to create the array then the array of specified 
		size is created with elements having undefined values. You can set the element values using <code>put</code> 
		array method.
		</p>
	
		<p>Following examples demonstrate how to create and initialize two different arrays with same size and values
		in two different ways.</p>
<pre><code>var arr1 = gls.byteArray ("10,20,30");

var arr2 = gls.byteArray (3);
for (var i=0; i < 3; i++)
	arr2.put (i, (i + 1) * 10);
</code></pre>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax">gls.ubyteArray (elements | size)</div>
	<div class="doc">Creates an array of GLubyte.</div>
	<div class="doc">
		<p>See <a href="#glscript_gls_object_method_byteArray">gls.byteArray</a> for more information.</p>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax">gls.shortArray (elements | size)</div>
	<div class="doc">Creates an array of GLshort.</div>
	<div class="doc">
		<p>See <a href="#glscript_gls_object_method_byteArray">gls.byteArray</a> for more information.</p>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax">gls.ushortArray (elements | size)</div>
	<div class="doc">Creates an array of GLushort.</div>
	<div class="doc">
		<p>See <a href="#glscript_gls_object_method_byteArray">gls.byteArray</a> for more information.</p>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax">gls.intArray (elements | size)</div>
	<div class="doc">Creates an array of GLint.</div>
	<div class="doc">
		<p>See <a href="#glscript_gls_object_method_byteArray">gls.byteArray</a> for more information.</p>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax">gls.uintArray (elements | size)</div>
	<div class="doc">Creates an array of GLuint.</div>
	<div class="doc">
		<p>See <a href="#glscript_gls_object_method_byteArray">gls.byteArray</a> for more information.</p>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax">gls.floatArray (elements | size)</div>
	<div class="doc">Creates an array of GLfloat.</div>
	<div class="doc">
		<p>See <a href="#glscript_gls_object_method_byteArray">gls.byteArray</a> for more information.</p>
	</div>
   </div>
   
   <div class="method">
	<div class="syntax">gls.doubleArray (elements | size)</div>
	<div class="doc">Creates an array of GLdouble.</div>
	<div class="doc">
		<p>See <a href="#glscript_gls_object_method_byteArray">gls.byteArray</a> for more information.</p>
	</div>
   </div>
   
   <!--<div class="method">
	<div class="syntax">gls.log (message)</div>
	<div class="doc">
		Prints the message. <span class="deprecated">Deprecated since version 0.0.0.2.
		Please use console.log instead.</span>
	</div>
   </div>-->
</div> <!-- end methods -->
  
<a name="glscript_gl_object"><h4>gl Object</h4></a>
<p>
 <code>gl</code> object is the interface to all OpenGL APIs. All OpenGL APIs are called in the context of this object.
 An example in JavaScript is shown below:
<pre><code> gl.glClearColor (1.0, 1.0, 1.0, 1.0);
 gl.glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
</code></pre>
</p>
<p>
<code>gl</code> is auto accessible object, which means it is not necessary to specify <code>gl</code> when calling any of its methods.
Auto accessible objects are added with <code>SCRIPTITEM_GLOBALMEMBERS</code> flag in the script engine. The previous example can be 
rewritten as:
<pre><code> glClearColor (1.0, 1.0, 1.0, 1.0);
 glClear (GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
</code></pre>
This style is more portable to the actual C API. For list of methods, please refer the OpenGL API reference.
</p>

<!-- gl methods -->
<a name="glscript_gl_object_methods"><h5>gl Object Methods</h5></a>
<div class="methods">	  
 <div class="method">
  <div class="syntax">gl.flush ()</div>
  <div class="doc">
  Swaps the OpenGL back buffer with the screen buffer to force display.
  This method should be called somewhere at the end of drawing code, otherwise nothing is displayed on the
  screen.
  </div>
 </div>
 <div class="method">
  <div class="syntax">gl.gl* ()</div>
  <div class="doc">
  * Please refer the <a href="http://www.opengl.org/documentation/" target="_blank">OpenGL API reference</a>&nbsp;... for 
  all methods.
  </div>
 </div>
</div>
<!-- gl methods end -->

<a name="glscript_console_object"><h4>console Object</h4></a>
<p>
<code>console</code> object is used to perform logging and displaying messages on console window.
</p>
<h5>console Object Methods</h5>
<div class="methods">
  <div class="method">
	<div class="syntax">console.log (message)</div>
    <div class="doc">Logs a message to console window.</div>
  </div>
  <div class="method">
	<div class="syntax">console.warn (message)</div>
    <div class="doc">Logs a warning message to console window.</div>
  </div>
  <div class="method">
	<div class="syntax">console.error (message)</div>
    <div class="doc">Logs an error message to console window.</div>
  </div>
  <div class="method">
	<div class="syntax">console.clear ()</div>
    <div class="doc">Clears the console window.</div>
  </div>
</div>

<!-- Inbuild Interfaces -->
<a name="glscript_inbuilt_interfaces"><h4>Inbuilt Interfaces</h4></a>
<p>glScript provides following inbuilt interfaces that are always available in your script. 
These interfaces cannot be used directly. You must create an object using standard ways, 
which will return you one of these interfaces that can be used. The interface describes a set of properties 
and methods that the object implements.
</p>
<ul>
<!--
<li>_GLScript_Engine</li>
<li>_GLScript_Context</li>
-->
<li>_GLScript_Array</li>
<!--<li>_GLScript_Console</li>-->
</ul>

<!--
<h5>_GLScript_Engine Interface</h5>
<p>
<code>_GLScript_Engine</code> interface describes the interface for the glScript internal engine. The inbuilt 
<code>gls</code> object is based on this interface. Please refer the <code>gls</code> object properties and 
methods for details.
</p>

<h5>_GLScript_Context Interface</h5>
<p>
<code>_GLScript_Context</code> interface describes the interface for the OpenGL API. The inbuilt 
<code>gl</code> object is based on this interface. Please refer the <code>gl</code> object properties 
and methods for details.
</p>
-->

<a name="glscript__GLScript_Array_interface"><h5>_GLScript_Array Interface</h5></a>
<p>
<code>_GLScript_Array</code> interface describes the interface for all typed arrays used in glScript. You can
create arrays using the inbuilt <code>gls</code> object by calling any of its <code>gls.*Array()</code>
methods. All of these methods create a specific type of array object and returns its
<code>_GLScript_Array</code> interface.
</p>

<h5>_GLScript_Array Interface Properties</h5>
<div class="properties">
  <div class="property">
	<div class="syntax">type (Readonly)</div>
    <div class="doc">Returns the internal OpenGL <i>type</i> of array.</div>
  </div>
  <div class="property">
	<div class="syntax">length (Readonly)</div>
    <div class="doc">Returns the length of array.</div>
  </div>
</div>

<h5>_GLScript_Array Interface Methods</h5>
<div class="methods">
  <div class="method">
	<div class="syntax">get (index)</div>
    <div class="doc">Returns the element value at specified index.</div>
  </div>
  <div class="method">
	<div class="syntax">put (index, value)</div>
    <div class="doc">Sets the element value at specified index.</div>
  </div>
</div>

<!--
<h5>_GLScript_Console Interface Methods</h5>
<p>
GLScript_Console interface describes the interface for the inbuilt <code>console</code> object.
Please refer the <code>console</code> object properties and methods for details.
</p>
-->

<!-- glscript events begin -->
<a name="glscript_events"><h4>glScript Events</h4></a>

<p>glScript engine communicates with gls scripts using events. Events are defined as global functions or methods 
in the script that has predetermined name as recognized by the glScript engine. glScript engine calls these methods at 
appropriate times. For e.g. event named <code>gls_renderScene</code> is called to draw the scene. All events begin with
<code>gls_</code> prefix.
</p>

<a name="glscript_basic_events"><h5>glScript Basic Events</h5></a>
 <div class="methods">
 
 <div class="method">
  <div class="syntax">gls_init ()</div>
   <div class="doc">
    Called to perform OpenGL initialization specific to the running script.
   </div>
 </div>

 <div class="method">
  <div class="syntax">gls_terminate ()</div>
   <div class="doc">
    Called before the script is terminated so it can perform necessary cleanup.
   </div>
 </div>
 
 <div class="method">
  <div class="syntax">gls_renderScene ()</div>
  <div class="doc">   
	Called to draw the scene. This method is called only if native drawing mode is disabled.
  </div>
 </div> 
 
 <div class="method">
  <div class="syntax">gls_timer ()</div>
   <div class="doc">
    Called on each timer event that the engine sets internally based on frame rate set during configuration
	phase. This is usually used for animation and is otherwise called as 'tick' event.
	<p><b>This method is reserved for future use.</b></p>
   </div>
 </div>

 <div class="method">
  <div class="syntax">gls_error (error_code, error_description)</div>
  <div class="doc">
   Called whenever an error is encountered in glScript engine or some extension but not in the script itself.
   <p><b>This method is reserved for future use.</b></p>
  </div>
 </div>

<a name="glscript_ui_events"><h5>glScript UI Events</h5></a> 
 <div class="method">
  <div class="syntax">gls_mouseDown (button, x, y)</div>
  <div class="doc">
   Called whenever mouse button is pressed on the screen.   
  </div>
  <div class="doc">   
	<p><code>button</code>: Integer value identifying the button that was pressed.</p>
	<p><code>x</code>: X coordinate of the point where the mouse was pressed.</p>
	<p><code>y</code>: Y coordinate of the point where the mouse was pressed.</p>
  </div>
 </div>
 
 <div class="method">
  <div class="syntax">gls_mouseUp (button, x, y)</div>
  <div class="doc">
   Called whenever mouse button is released on the screen.
  </div>
  <div class="doc">   
	<p><code>button</code>: Integer value identifying the button that was released.</p>
	<p><code>x</code>: X coordinate of the point where the mouse was released.</p>
	<p><code>y</code>: Y coordinate of the point where the mouse was released.</p>
  </div>
 </div>
 
 <div class="method">
  <div class="syntax">gls_mouseMove (x, y)</div>
  <div class="doc">
   Called whenever mouse pointer is moved on the screen.
  </div>
  <div class="doc">   
	<p><code>x</code>: X coordinate of the point where the mouse was moved.</p>
	<p><code>y</code>: Y coordinate of the point where the mouse was moved.</p>
  </div>
 </div>
 
 <div class="method">
  <div class="syntax">gls_keyDown (key_code)</div>
  <div class="doc">
   Called whenever a key is pressed down.
  </div>
  <div class="doc">   
	<p><code>key_code</code>: Integer value identifying the key that was pressed.</p>
  </div>
 </div>
 
 <div class="method">
  <div class="syntax">gls_keyUp (key_code)</div>
  <div class="doc">
   Called whenever a pressed key is released.
  </div>
  <div class="doc">   
	<p><code>key_code</code>: Integer value identifying the key that was released.</p>
  </div>
 </div>
 
 <div class="method">
  <div class="syntax">gls_keyPress (key_code)</div>
  <div class="doc">
   Called whenever a key is pressed. This event is called repeatedly as long as the key remains pressed.
  </div>
  <div class="doc">
	<p><code>key_code</code>: Integer value identifying the key that was pressed.</p>
  </div>
 </div>
 
</div>
<!-- end glscript events -->

<div class="footer">
OpenGL is a registered trademark of Silicon Graphics, Inc.
</div>
</body>
</html>
